PsL Monthly 1993 December/PSL Monthly Shareware CD-ROM (December 1993).iso/prgmming/dos/pascal/strlink.com/STRLINK.DOC

Text File | 1989-09-01 | 19.0 KB | 449 lines

                                    STRLINK OBJECT
                                     Version 1.01
                                   1 September 1989

                                   Rob Rosenberger
                                  Barn Owl Software
                                     P.O. Box 74
                                 O'Fallon, IL  66269
                                    [phone]


               This Turbo Pascal v5.5 OOP object implements a linked list
          of strings.  You no longer have to read a text file more than one
          time: you can now let an OOP variable of StrLinkList type read it
          into memory.  You can sort text files based on varying criteria,
          remove redundant strings, etc.

               This link list of strings offers an extra added bonus.  Each
          string on the list takes up only as much space as it absolutely
          requires.  This is true even if you change the size of the string
          after putting it on the list.  (You can always inspect the code
          if you want to see how it was accomplished.)

               And because it's OOP, you can create a descendent object if
          you have special needs.  If any of the code is ever updated, you
          can usually upgrade to the new version ── without changing a line
          of your descendent code.  (Assuming the calls themselves in the
          ancestor object haven't changed, of course.)


          UNIT NAME


               The name of the main unit is "StrLink".  You should put this
          in any program or unit of your own that needs access to variables
          of type StrLinkList.


          CONDITIONAL DIRECTIVES


               {$IFDEF TPRO5}

               The StrLink unit can optionally use TurboPower Software's
          TPRO5 toolkit.  TPRO5 offers some extra efficiency & speed for
          string link lists.  If you do NOT have TPRO5, you must change the
          '$' to a '.' so the proper code will compile.
               I encourage you to write or call TurboPower for a brochure
          about their products.  I actually pity you if you aren't using
          their toolkits.  TPRO5 contains 50,000+ lines of source code in
          over 30 units, and TurboPower is coming out soon with OPRO, the
          Object Professional Toolkit.  You can contact TurboPower at P.O.
          Box 66747, Scotts Valley, CA 95066, or call [phone].  Be
          sure to tell them I said hi.

          STRLINK OBJECT                                        Page 2 of 8



          USES


               The StrLink unit USES the following units:

                    {$IFDEF TPRO5}
                        TpString,
                    {$ENDIF}
                    Objects,
                    ObjectA,
                    StrObj;

               The TpString unit is supplied with the TurboPower Software
          TPRO5 toolkit.  Please see the section on conditional compilation
          directives for more information about this powerful toolkit.
               The Objects unit is on Turbo Pascal v5.5 disk #3.  It imple-
          ments the foundation of a singly linked list object.
               The ObjectA unit is included in this file IF this was pulled
          down from a BBS.  If it was pulled down from CompuServe, then you
          must also download OBJA.ARC from BPROGA forum LIBrary 1.  ObjectA
          builds on the Objects unit by offering a more powerful descendent
          object for singly linked lists.
               The StrObj unit is included with StrLink.  It implements the
          foundation for a string object.  Each string object will take up
          only as much room on the heap as it absolutely requires.


          TYPES


          SortedOrderType = (ForwardOrder,
                             ReverseOrder,
                             AscendingOrder,
                             DescendingOrder);

          StrLinkList
           = OBJECT(LinkList)
             CurrentStrPtr     : StrObjectPtr;
             UniqueStringsOnly : BOOLEAN;
             SortedOrder       : SortedOrderType;
             CaseMatters       : BOOLEAN;

             CONSTRUCTOR Init(UniqueStrings : BOOLEAN;
                              SortSpecifier : SortedOrderType;
                              IgnoreCase    : BOOLEAN);

             FUNCTION  GetSpecificString(NodePos : LONGINT) : STRING;
             PROCEDURE DeleteSpecificString(NodePos : LONGINT);

             FUNCTION  ReadStrings(TheFilename : STRING) : WORD; VIRTUAL;
             FUNCTION  WriteStrings(TheFilename : STRING;
                                    AppendFile  : BOOLEAN) : WORD; VIRTUAL;

             FUNCTION  AddString(TheStr : STRING) : BOOLEAN;

          STRLINK OBJECT                                        Page 3 of 8



             PROCEDURE DeleteString(TheStr : STRING);
             FUNCTION  Exists(TheStr : STRING) : BOOLEAN;
             FUNCTION  ExistsSubstring(TheSubStr : STRING) : BOOLEAN;
             PROCEDURE DeleteStringsWithoutSubstring(TheSubStr  : STRING;
                                                     IgnoreCase : BOOLEAN);
             PROCEDURE DeleteStringsWithSubstring(TheSubStr  : STRING;
                                                  IgnoreCase : BOOLEAN);
             PROCEDURE DeleteDuplicates;
             PROCEDURE DeleteLeadNullStrings;
             PROCEDURE DeleteNullStrings;
             PROCEDURE DeleteTrailNullStrings;

             FUNCTION  TotalLengthOfStrings : LONGINT;

             PROCEDURE InitCurrent;
             FUNCTION  CurrentString : STRING;
             PROCEDURE ChangeCurrentString(NewStr : STRING);
             FUNCTION  FirstString : STRING;
             FUNCTION  LastString : STRING;
             PROCEDURE Advance;
             PROCEDURE Retreat;
             FUNCTION  MoreStrings : BOOLEAN;
             FUNCTION  NoMoreStrings : BOOLEAN
             END;

          STRLINK OBJECT                                        Page 4 of 8



          PROCEDURES & FUNCTIONS


          CONSTRUCTOR Init(UniqueStrings : BOOLEAN;
                           SortSpecifier : SortedOrderType;
                           IgnoreCase    : BOOLEAN);

               Initializes the StrLinkList instantiation.  UniqueStrings
          dictates if the list should ignore duplicate strings.  IgnoreCase
          dictates if the strings should be viewed as all uppercase, even
          though they will be stored as upper/lowercase.
               SortSpecifier dictates how the list is sorted.  ForwardOrder
          means strings will be added to the END of the list.  This is the
          same as reading a regular text file.  ReverseOrder means strings
          will be added to the BEGINNING of the list.  This would be like
          reading a text file backwards.  AscendingOrder dictates that the
          list will be sorted in ascending order.  DescendingOrder dictates
          that the list will be sorted in descending order.
               The IgnoreCase boolean is important if you choose to sort
          the list in ascending/descending order.  If IgnoreCase is FALSE,
          "BBBB" will come before "aaaa".  When IgnoreCase is TRUE, all
          strings are viewed as uppercase.  But don't worry, they're stored
          exactly as they are.  IgnoreCase is important only during string
          comparisons.
               As a good programming practice, you should call Init() as a
          function, not as a procedure.  (See TP OOP guide pp. 106-7, and
          TP reference guide ch. 15, for more details.)  The boolean result
          of Init(), if called as a function, is the success or failure of
          the object's construction.


          DESTRUCTOR  Done;

               This destructor is INHERITED from an ancestral object.  It
          completely removes all strings from the list and frees up their
          associated memory.  You must call this destructor/procedure when
          you're finished with the list.  (You can "flush" the list for a
          new purpose by calling Done, then calling Init once more.)


          FUNCTION  GetSpecificString(NodePos : LONGINT) : STRING;

             This function returns a string from the StrLinkList based on
          the position of a particular string in the list.  This is useful
          for people who use TurboPower Software's TPRO5 TpPick unit, for
          example.  The position is represented by NodePos.  This function
          returns a null string if NodePos is <= 0 or if it is > the last
          node on the list.  The CurrentString function will return this
          string after you use this function.

          STRLINK OBJECT                                        Page 5 of 8



          PROCEDURE DeleteSpecificString(NodePos : LONGINT);

             This procedure deletes a string from the StrLinkList based on
          the position of the string in the list, represented by NodePos.
          It does nothing if NodePos is <= 0 or if it is > the last string
          position on the list.  The CurrentString function points to NO
          string after this call.


          FUNCTION  ReadStrings(TheFilename : STRING) : WORD; VIRTUAL;

             Reads strings from TheFilename and adds them to the list.  The
          IORESULT value is returned as the result of this function, except
          in cases where the heap ceiling caves in, at which point a value
          of MAXINT is returned.
               This method is VIRTUAL ── you can expand on it with your own
          descendent objects.


          FUNCTION  WriteStrings(TheFilename : STRING;
                                 AppendFile  : BOOLEAN) : WORD; VIRTUAL;

             Writes all strings on the list to TheFilename.  The IORESULT
          value is returned as the result of this function.  AppendFile
          dictates if the strings should be appended to the end of a file
          if it already exists.  NOTE: the file must exist if AppendFile is
          set to TRUE.
               This method is VIRTUAL ── you can expand on it with your own
          descendent objects.


          FUNCTION  AddString(TheStr : STRING) : BOOLEAN;

             Adds a string to the list.  It does nothing if the string is
          redundant AND UniqueStrings was TRUE when you called Init.  The
          CurrentString function is undefined after calling this routine.
          (It may, or may not, point to the newly added string.)
               This method returns FALSE only if there is no more room on
          the heap to add the new string to the list.


          PROCEDURE DeleteString(TheStr : STRING);

             This procedure deletes the given string from the list.  It
          does nothing if the string doesn't exist.  The CurrentString
          function points to NO string after this call.


          FUNCTION  Exists(TheStr : STRING) : BOOLEAN;

             Determines if the given string is on the list.  This function
          is affected by the IgnoreCase declaration you specified when you
          called the Init() constructor.

          STRLINK OBJECT                                        Page 6 of 8



          FUNCTION  ExistsSubstring(TheSubStr : STRING) : BOOLEAN;

             Similar to the Exists function, this routine determines if a
          given substring is on the StrLinkList.  It searches every string
          on the list until it either finds the substring inside one of the
          strings, or it runs out of strings to search.  This function is
          TRUE if TheSubStr is a null string and at least one string exists
          on the list.
               This function is affected by the IgnoreCase declaration you
          specified when you called the Init() constructor.
               If the result is TRUE, CurrentString will return the first
          string on the list containing the given substring.


          PROCEDURE DeleteStringsWithoutSubstring(TheSubStr  : STRING;
                                                  IgnoreCase : BOOLEAN);

             This procedure deletes any string from the list that doesn't
          contain the given substring.  No strings will be deleted if the
          substring is a null string.  The IgnoreCase variable dictates
          whether upper/lower case is relevant during the search.  (This
          overrides the string comparison check you specified when you
          called Init.)


          PROCEDURE DeleteStringsWithSubstring(TheSubStr  : STRING;
                                               IgnoreCase : BOOLEAN);

             This procedure deletes any string from the list that DOES
          contain the given substring.  No strings will be deleted if the
          substring is a null string.  The IgnoreCase variable dictates
          whether upper/lower case is relevant during the search.  (This
          overrides the string comparison check you specified when you
          called Init.)


          PROCEDURE DeleteDuplicates;

               This procedure deletes duplicate strings from the list.  It
          does nothing if you specified unique strings during the call to
          the Init procedure.  This function is affected by the IgnoreCase
          declaration you specified when you called the Init() constructor.


          PROCEDURE DeleteLeadNullStrings;

               This procedure deletes leading null strings from the list.
          It's an easy way to strip out any leading blank lines from a text
          file.  Null strings that exist past the first non-null string in
          the list are left alone.

          STRLINK OBJECT                                        Page 7 of 8



          PROCEDURE DeleteNullStrings;

               This procedure deletes all null strings from the list.  It's
          an easy way to delete all the blank lines from a text file you
          just read from disk.


          PROCEDURE DeleteTrailNullStrings;

               This procedure deletes trailing null strings from the list.
          It's an easy way to delete blank lines from the end of a text
          file you just read from disk.


          FUNCTION  TotalLengthOfStrings : LONGINT;

               Returns the total length of the strings on the list.  This
          is much faster than calculating the total length with successive
          calls to LENGTH(GetCurrentString).  The CurrentString function
          points to NO string after this call.


          PROCEDURE InitCurrent;

               This function initializes the CurrentString so it returns
          the first first string on the list (assuming there is at least
          one string on the list).  The MoreStrings function must be used
          to test if there is at least one string on the list.


          FUNCTION  CurrentString : STRING;

               This function returns the current string pointed to in the
          list.  You must use the InitCurrent procedure to set the current
          string to the first string in the list.  CurrentString returns a
          null string if it points to no string.  (Use the MoreStrings and
          NoMoreStrings functions to determine if CurrentString points to a
          string.)


          PROCEDURE ChangeCurrentString(NewStr : STRING);

               Changes the current string to the new string.


          FUNCTION  FirstString : STRING;

               Returns the first String in the list.  It returns a null
          string if there are no strings in the list.  The CurrentString
          function will also return the first string after you call this
          function.

          STRLINK OBJECT                                        Page 8 of 8



          FUNCTION  LastString : STRING;

               Returns the last String in the list.  It returns a null
          string if there are no strings in the list.  The CurrentString
          function will also return the last string after you call this
          function.


          PROCEDURE Advance;

               This procedure simply moves the current string pointer to
          the next string in the list.  You should use the MoreStrings or
          NoMoreStrings functions to see if there is another string on the
          list after making this call.


          PROCEDURE Retreat;

               This procedure simply moves the current string pointer to
          the previous string in the list.  The CurrentString function
          points to NO string if you retreat past the first string on the
          list.  Use the MoreStrings or NoMoreStrings functions to see if
          there is another string on the list after making this call.


          FUNCTION  MoreStrings : BOOLEAN;

               Returns TRUE or FALSE, explaining if CurrentString points to
          a valid string in the list.  Should be used with the Advance and
          Retreat procedures.
               Special note:  MoreStrings tells you if CurrentString() is
          pointing to a string RIGHT NOW.  It does not tell you if there is
          another string waiting after the current string.


          FUNCTION  NoMoreStrings : BOOLEAN;

               The opposite of the MoreStrings function.  See above.

         ----------------end-of-author's-documentation---------------

                        Software Library Information:

                   This disk copy provided as a service of

                        The Public (Software) Library

         We are not the authors of this program, nor are we associated
         with the author in any way other than as a distributor of the
         program in accordance with the author's terms of distribution.

         Please direct shareware payments and specific questions about
         this program to the author of the program, whose name appears
         elsewhere in  this documentation. If you have trouble getting
         in touch with the author,  we will do whatever we can to help
         you with your questions. All programs have been tested and do
         run.  To report problems,  please use the form that is in the
         file PROBLEM.DOC on many of our disks or in other written for-
         mat with screen printouts, if possible.  The P(s)L cannot de-
         bug programs over the telephone.

         Disks in the P(s)L are updated monthly, so if you did not get
         this disk  directly from the P(s)L,  you should be aware that
         the files in this set may no  longer be the current versions.

         For a copy of the latest monthly software library newsletter
         and a list of the 1,900+ disks in the library, call or write

                        The Public (Software) Library
                              P.O.Box 35705 - F
                           Houston, TX 77235-5705
                               [phone]